package com.smart.community.work.service;

import java.time.LocalDate;
import java.util.List;
import java.util.Map;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.work.dto.CleaningAreaDTO;
import com.smart.community.work.dto.CleaningAreaQueryDTO;
import com.smart.community.work.dto.CleaningRecordQueryDTO;
import com.smart.community.work.dto.CleaningTaskCompleteDTO;
import com.smart.community.work.dto.CleaningTaskQueryDTO;
import com.smart.community.work.dto.CleaningTaskStartDTO;
import com.smart.community.work.entity.CleaningArea;
import com.smart.community.work.entity.CleaningRecord;
import com.smart.community.work.entity.CleaningTask;
import com.smart.community.work.vo.CleaningAreaVO;
import com.smart.community.work.vo.CleaningRecordVO;
import com.smart.community.work.vo.CleaningTaskVO;
import com.smart.community.work.vo.CleaningTaskDetailVO;

/**
 * 保洁管理服务接口
 * 
 * 严格按照《Java后端SpringBoot代码开发规范_重构版.md》Service规范实现：
 * - 继承IService：获得基础CRUD方法
 * - 方法命名：使用动词+名词形式，语义明确
 * - 参数验证：使用@Valid注解进行参数验证
 * - 异常处理：使用统一的异常处理机制
 * - 完整注释：所有方法都有完整的JavaDoc注释
 * 
 * @author Wu.Liang
 * @since 2025-01-30
 * @version 1.0.0
 */
public interface CleaningService extends IService<CleaningArea> {

    // ========================= 保洁区域管理 =========================


    /**
     * 分页查询保洁区域（使用DTO）
     * 
     * @param queryDTO 查询参数DTO
     * @return 保洁区域分页数据
     * @throws Exception 异常
     */
    IPage<CleaningAreaVO> selectCleaningAreaPage(CleaningAreaQueryDTO queryDTO) throws Exception;

    /**
     * 创建保洁区域
     * 
     * @param areaDTO 区域DTO
     * @return 区域ID
     * @throws Exception 异常
     */
    Long createCleaningArea(CleaningAreaDTO areaDTO) throws Exception;

    /**
     * 根据ID查询保洁区域详情
     * 
     * @param id 区域ID
     * @return 保洁区域详情
     * @throws Exception 异常
     */
    CleaningAreaVO selectCleaningAreaById(Long id) throws Exception;


    /**
     * 更新保洁区域
     * 
     * @param cleaningArea 保洁区域信息
     * @return 更新结果
     * @throws Exception 异常
     */
    Boolean updateCleaningArea(CleaningArea cleaningArea) throws Exception;

    /**
     * 删除保洁区域
     * 
     * @param id 区域ID
     * @param updateBy 更新人ID
     * @return 删除结果
     * @throws Exception 异常
     */
    Boolean deleteCleaningArea(Long id, Long updateBy) throws Exception;

    // ========================= 保洁任务管理 =========================


    /**
     * 分页查询保洁任务（使用DTO）
     * 
     * @param queryDTO 查询参数DTO
     * @return 保洁任务分页数据
     * @throws Exception 异常
     */
    IPage<CleaningTaskVO> selectCleaningTaskPage(CleaningTaskQueryDTO queryDTO) throws Exception;

    /**
     * 根据用户ID查询保洁任务
     * 
     * @param userId 用户ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 保洁任务列表
     * @throws Exception 异常
     */
    List<CleaningTaskVO> selectCleaningTaskByUserId(Long userId, LocalDate startDate, LocalDate endDate) throws Exception;

    /**
     * 创建保洁任务
     * 
     * @param cleaningTask 保洁任务信息
     * @return 创建结果
     * @throws Exception 异常
     */
    Boolean createCleaningTask(CleaningTask cleaningTask) throws Exception;

    /**
     * 更新保洁任务
     * 
     * @param cleaningTask 保洁任务信息
     * @return 更新结果
     * @throws Exception 异常
     */
    Boolean updateCleaningTask(CleaningTask cleaningTask) throws Exception;

    /**
     * 分配保洁任务
     * 
     * @param taskId 任务ID
     * @param userId 用户ID
     * @param updateBy 更新人ID
     * @return 分配结果
     * @throws Exception 异常
     */
    Boolean assignCleaningTask(Long taskId, Long userId, Long updateBy) throws Exception;

    /**
     * 删除保洁任务
     * 
     * @param id 任务ID
     * @param updateBy 更新人ID
     * @return 删除结果
     * @throws Exception 异常
     */
    Boolean deleteCleaningTask(Long id, Long updateBy) throws Exception;

    /**
     * 获取保洁任务详情
     * 
     * @param id 任务ID
     * @return 任务详情
     * @throws Exception 异常
     */
    CleaningTaskVO getCleaningTaskDetail(Long id) throws Exception;

    /**
     * 获取保洁任务详细信息（包含执行记录）
     * 
     * @param id 任务ID
     * @return 任务详细信息
     * @throws Exception 异常
     */
    CleaningTaskDetailVO getCleaningTaskDetailInfo(Long id) throws Exception;

    /**
     * 开始执行保洁任务
     * 
     * @param startDTO 开始执行参数
     * @param currentUserId 当前用户ID
     * @return 执行结果
     * @throws Exception 异常
     */
    Boolean startCleaningTask(CleaningTaskStartDTO startDTO, Long currentUserId) throws Exception;

    /**
     * 完成保洁任务
     * 
     * @param completeDTO 完成参数
     * @param currentUserId 当前用户ID
     * @return 完成结果
     * @throws Exception 异常
     */
    Boolean completeCleaningTask(CleaningTaskCompleteDTO completeDTO, Long currentUserId) throws Exception;

    // ========================= 保洁记录管理 =========================


    /**
     * 分页查询保洁记录（使用DTO）
     * 
     * @param queryDTO 查询参数DTO
     * @return 保洁记录分页数据
     * @throws Exception 异常
     */
    IPage<CleaningRecordVO> selectCleaningRecordPage(CleaningRecordQueryDTO queryDTO) throws Exception;

    /**
     * 分页查询保洁记录（带权限控制）
     * 根据用户角色进行权限控制：
     * - 物业管理员或保洁管理：可以查看所有关联物业公司所属社区的数据
     * - 其他角色：无法查看任何数据
     * 
     * @param queryDTO 查询参数DTO
     * @param currentUserId 当前用户ID
     * @return 保洁记录分页数据
     * @throws Exception 异常
     */
    IPage<CleaningRecordVO> selectCleaningRecordPageWithPermission(CleaningRecordQueryDTO queryDTO, Long currentUserId) throws Exception;

    /**
     * 根据用户ID查询保洁记录
     * 
     * @param userId 用户ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 保洁记录列表
     * @throws Exception 异常
     */
    List<CleaningRecordVO> selectCleaningRecordByUserId(Long userId, LocalDate startDate, LocalDate endDate) throws Exception;

    /**
     * 提交保洁记录
     * 
     * @param cleaningRecord 保洁记录信息
     * @return 提交结果
     * @throws Exception 异常
     */
    Boolean submitCleaningRecord(CleaningRecord cleaningRecord) throws Exception;

    /**
     * 验收保洁记录
     * 
     * @param recordId 记录ID
     * @param score 评分
     * @param remark 验收备注
     * @param updateBy 更新人ID
     * @return 验收结果
     * @throws Exception 异常
     */
    Boolean approveCleaningRecord(Long recordId, Integer score, String remark, Long updateBy) throws Exception;

    /**
     * 更新保洁记录
     * 
     * @param cleaningRecord 保洁记录信息
     * @return 更新结果
     * @throws Exception 异常
     */
    Boolean updateCleaningRecord(CleaningRecord cleaningRecord) throws Exception;

    /**
     * 删除保洁记录
     * 
     * @param id 记录ID
     * @param updateBy 更新人ID
     * @return 删除结果
     * @throws Exception 异常
     */
    Boolean deleteCleaningRecord(Long id, Long updateBy) throws Exception;

    // ========================= 统计查询 =========================

    /**
     * 获取保洁统计信息
     * 
     * @param propertyCompanyId 物业公司ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 统计信息
     * @throws Exception 异常
     */
    Map<String, Object> getCleaningStatistics(Long propertyCompanyId, LocalDate startDate, LocalDate endDate) throws Exception;

    /**
     * 获取用户保洁统计
     * 
     * @param userId 用户ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 用户统计信息
     * @throws Exception 异常
     */
    Map<String, Object> getUserCleaningStatistics(Long userId, LocalDate startDate, LocalDate endDate) throws Exception;
}
